Skip to content

feat(server): relay only the protocol, lift limits only for paired browsers - #71

Merged
enricobuehler merged 6 commits into
mainfrom
feat/server-protocol-only
Nov 5, 2026
Merged

enricobuehler merged 6 commits into
mainfrom
feat/server-protocol-only

Conversation

@enricobuehler

Copy link
Copy Markdown
Member

The second half of hardening the page server for people who expose it, stacked on #70 (design: planning design/web-client-exposure.md). The host half is unom/punktfunk #2293; this pins punktfunk-core to that branch's first commit, which is all the server needs from it.

What a visitor whose browser is not paired with a host gets from an exposed server, before and after:

Before After
HTTPS requests to any private address yes no: one fixed probe per typed address, metered, answer not returned
WebTransport to any private address and port yes no
Host names and LAN addresses yes names only
Wake a PC yes no
Knock or try a PIN yes; read as local behind a proxy 4 at a time, 20 an hour; a current host always treats it as the internet
Block paired players' streams yes, 16 sockets no
Use the page under an impostor's certificate after one click no page at a public address without a real certificate

Commits

  • feat(server): tell hosts who the visitor is — the strictest of the TCP peer and every forwarded address, on every relayed request and bridge dial as pf-client-addr; unknown behind a proxy that names nobody.
  • feat(server): relay only the protocol, only to proven hosts — the relay forwards only routes in core's table, and reaches an address the operator did not list only after fetching its plane itself and checking the signature of the identity that served it.
  • feat(server): give paired browsers a pass, strangers a lane — a browser whose token a host accepted gets a pass (only its hash is stored). The pass buys the paired bridge pool, wake and freedom from the rate limit. A token, and the device login itself, go only over a connection with the identity the browser paired with (pf-host). Listener caps and timeouts as on the host.
  • feat(server): refuse a self-made certificate to the internet — and deploy/compose.public.yaml: Caddy with a real certificate in front, one command.
  • docs, and the pin.

Breaking

  • Port forward plus the default self-signed certificate no longer serves the client outside your network. A browser there gets a page saying why. Use Tailscale (compose.tailscale.yaml) or a domain with a certificate (DOMAIN=… docker compose -f compose.public.yaml up -d).
  • Behind a reverse proxy, send X-Forwarded-For (nginx: proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;). Without it every visitor is unknown, and a host treats them as coming from the internet.
  • A browser that is not paired with a host can no longer wake it, and is rate-limited.
  • A tab left open across the update has to be reloaded once.

Checked

  • server/: fmt, clippy -D warnings --locked, 46 tests --locked against the pinned revision.
  • Page: tsc in both workspaces, 90 + 4 tests.
  • compose.public.yaml's Caddy with its internal issuer on localhost, in front of this branch's server: the page loads with HSTS, Caddy's X-Forwarded-For reaches the server and replaces a forged one, the bridge upgrade passes.

Not checked

  • Nothing ran in a browser beyond page load: no stream, pairing, wake or bridge session against a real host. Owed on glass on three engines before a release.
  • compose.public.yaml with a real domain and certificate.
  • The 10 s TLS deadline, the 30 s header deadline and the three-minute pairing session have no test.

The bridge named its TCP peer as the client and the API relay named
nobody. Behind a proxy, a published Docker port or a tunnel that peer
is private, so a knock from the internet read as one from home, and
every visitor shared the server's address in a host's limits.

The visitor is now the strictest of the peer and every address in
X-Forwarded-For and Forwarded, named by the right-most public one; an
entry a caller made up can only tighten it. Behind TLS=off a request
with no forwarding header is unknown, and so is one with an entry that
is not an address. An IPv6 peer on one of this machine's own /64s is at
home. Every relayed request and bridge dial carries it as
pf-client-addr.
The relay carried any method and path to any private address and port,
and the bridge dialled any of them: an open door into the LAN for
anyone who reached the page, and a way for one LAN device to pose as a
host.

A relayed request now takes only a route in core's table: the open four,
and a paired device's own with its token. An address the operator did
not list, typed or found over mDNS, is reached only once this server
has fetched its plane itself and checked that the identity serving its
TLS signed it. Anything else hears that one request and nothing more
for a minute. Typed and advertised addresses must be on a home network
and never loopback. Proven pins and kept clients stop at 64.
A device token proves a browser to a host, never to this server, so
the server could not tell a paired browser from a stranger and held
every visitor to the same limits. A pass, minted only when a host
takes the token, lets the server meter strangers, pool the bridge
and keep wake and plane addresses for paired browsers.

A token, and the device exchange that earns one, reach only the host
the browser paired with: the page names it in pf-host and the relay
checks the TLS leaf. Per-address limits count an IPv6 /64 as one.

The listener caps connections in all and, when it ends TLS itself,
per peer, with handshake and header deadlines.
A browser cannot pin a self-made certificate, so at a public address
nothing tells this server from an impostor, and the impostor would
collect the device key's signatures. A browser that reaches it
straight from the internet gets one static page saying so.

compose.public.yaml makes the supported way one command: Caddy with
a real certificate in front, the server on the host's network.

BREAKING CHANGE: a port forward to a self-signed server no longer
serves the client outside your network. Use Tailscale, or a domain
with a certificate (deploy/compose.public.yaml).
The Tailscale shape needs two files and two settings before its
first start, TLS_NAMES holds addresses as well as domains, and a
proxied page on a domain the host does not list pairs by PIN.
The server now reads the paired-route table, the address classes and the plane attestation check from punktfunk-core, which that commit adds. packages/stream keeps its own pin: it moves with the wire.
@enricobuehler
enricobuehler changed the base branch from fix/server-origin-gates to main November 5, 2026 22:04
@enricobuehler
enricobuehler merged commit e428b56 into main Nov 5, 2026
7 checks passed
@enricobuehler
enricobuehler deleted the feat/server-protocol-only branch November 5, 2026 22:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant